ADDRESS BOOK CONVERSION PROGRAM

1       Introduction
This program will convert virtually any Database file into the format 
required for the Address Book program. All you have to do is set up a 
simple text file to specify how you want the lines in your Database file to be 
mapped onto fields in the Address Book file.

In particular this program has been designed to handle the following 
situations:

o       More than one line in the Database file corresponding to the same 
        field in Address Book;

o       Names entered in the Database in the form of forename(s) followed 
        by surname or surname followed by forename(s), with any 
        separator, or surname and forename(s) entered on separate lines;

o       Multiple names in the same entry, with any separator.

2       Installation
Copy the file CONVADD.OPA to \APP on any drive. Then install 
CONVADD using the Install (Psion-I) command on the System screen. 
The program's icon will then appear with all Database files listed beneath 
it.

3       Creating Label File
You must create a label mapping file for each Database file you wish to 
convert. This must be a text file in the same directory and with the same 
name as the file to be converted, but with extension ".LAB".

This file specifies:

o       Which Address Book field each line of your Database file is to be 
        mapped to;

o       Which line contains the Name:, and how this is laid out.

The line corresponding to the name should be of the form:

Surname:, followed by separator, followed by Forename:
or:
Forename:, followed by separator, followed by Surname:

Alternatively if surname and forename are on separate lines then the 
corresponding lines in the label file should contain the labels:

Surname:
Forename:

The other lines in the label file should contain one of the following labels:

Organisation:
Home:
Work:
Fax:
Mobile:
Email:
Address:
Notes:

However you can leave a line blank if you do not want data from the 
corresponding field to be carried into the Address Book file.

The same label can appear on more than one line. In this case the data 
from the corresponding fields will be combined, with spaces separating the 
contributions from each field.

As an example, if entries in your Database file look something like:

        Name:     Smith, John Peter
        Phone:    0123 45678
        Address:  5, The Avenue, Newtown,
                  Oldshire, NT7 1AB
        Family:   Sister: Anne
        Notes:    Company Secretary

then a suitable label file might look like:

Surname:,Forename:
Home:
Address:
Address:
Notes:
Notes:

and produce the following result after conversion:
Name:     John Peter Smith
Home:     0123 45678
Address:  5, The Avenue, Newtown,
          Oldshire, NT7 1AB
Notes:    Sister: Anne Company Secretary

Note that while the second address line in the Database file does not have 
a label, the corresponding line in the label file must contain a label, 
otherwise the data from this line would be discarded.
As a further example, if the first line in your Database entries is a name in 
the following form:

        Name:   John Peter Smith

then the first line in the label file should be:

Forename: Surname:

One way of producing the label file would be to print a single entry of your 
Database to a file, setting Show Blank Lines to "Yes". You can then use this 
as a starting point for editing into the required form, using Word or a text 
editor. NOTE if you use Word to create or edit the label file you must save 
it as Text.

3       Converting
Having set up the label file you can now convert your database. Just 
highlight the required file beneath the conversion program icon and press 
Enter. The program displays a banner message, and a running count of 
records processed.
The program creates a new file in the \ADD directory on the same drive as 
the original Database file (which is not changed). The new file has the 
same name as the Database, but with extension ".ADD". If the directory 
does not already exist it will be created automatically.

This file should now appear under the Address Book icon (see User Guide 
for details of how to install Address Book). The file can be opened by the 
Address Book application in the normal way. The first time the file is 
opened there will be a delay while the index table is created; this will not 
happen when the file is opened on subsequent occasions (provided a clean 
exit was previously performed).

4       Further Options
The above procedure will be adequate for converting a good many 
Databases. However the conversion program does have extra features 
providing more sophisticated control. You should consider these if the 
following apply:

o       You have entries in your Database with more than one name;

o       Your Database has additional fields forming part of addresses which 
        you wish to print correctly on envelopes.

5       Multiple Names
If you have entries with multiple names then you must specify the 
character you use to separate the individual names. You do this by putting 
it at the end of the line in the label file which specifies the layout of your 
names.

For example if the first line of your Database entries contains one or more 
names separated by semicolons:

        Name:   Fred Bloggs; Joe Brown; Peter Smith

then the first line of the label file should be:
Forename: Surname:;

The conversion program would then create three linked entries. Fred 
Bloggs would be the 'parent', and Joe Brown and Peter Smith would be 
linked to it. See the User Guide for an explanation of linked entries.

If you use line breaks (i.e. Shift-Enter) to separate your names then you do 
not specify this explicitly in the label file; the program assumes this as the 
default.

6       Specifying Separators
As described above, the program normally puts a single space between 
components of a single Address Book field which have been combined 
from several fields in the Database. However this may not be satisfactory 
in all cases, particularly where the fields form part of an address to be 
printed on an envelope. Address Book requires that the individual 
components of an address which are to be printed on separate lines are 
separated by  commas.

You can specify the separator you wish to be used before the contents of a 
particular field in your Database by prefixing the corresponding label with 
it. For example if your Database contains lines of the following form:

        Address:  17, The High St
        Town:     Newtown
        Postcode: NT1 7AB

then the label file should contain the lines:

Address:
,Address:
,Address:

After conversion this would result in:

Address:        17, The High St, Newtown, NT1 7AB

As a further example consider the following Database entry:

        Address:  34, The Avenue,
                  Firlands Estate
        Town:     Newtown
        Postcode: NT1 7AB

Since there is already a comma at the end of the first Address: line no 
additional separator is required for the second Address: line. Hence the 
label file should look like:

Address:
Address:
,Address:
,Address:

However if your entries looked like:

        Address:  34, The Avenue
                  Firlands Estate
        Town:     Newtown
        Postcode: NT1 7AB

i.e. no comma separating the two Address: lines, then the separator would 
be required for the second Address: label:

Address:
,Address:
,Address:
,Address:

7       Limitations
The program can fully convert Database files with up to 31 fields. Files 
with larger numbers of fields can be handled, but data in the 32nd and later 
fields will be lost.

Fields in Address Book cannot exceed 255 characters (240 for the Address: 
field). If the total contributions (including separators) from the Database 
for any field exceed this limit, the data will be truncated.

8       Problems
The program does not contain any sophisticated error handling or 
recovery. Most likely causes of problems are:

o       Missing or incorrectly named label file, manifesting as "File does 
        not exist";

o       Label file invalid format (e.g. Word file rather than Text file), 
        manifesting as "Record too large".

o       Insufficient space for output Address Book file, manifesting as "Disk 
        full".

o       Insufficient free memory to run program, manifesting as "No 
        system memory".

9       Use of this Program and Disclaimer
This program may be used freely for the purposes of evaluating the 
Address Book program. There is no separate registration fee for using this 
conversion  program in conjunction with Address Book, but see the 
Address Book User Guide for registration details for that program.

While I have taken reasonable care in producing this program I cannot be 
held responsible for any loss or damage arising from its use.
If you do experience difficulties I will try to help. I can be contacted at:

John Dawson
19, St Edward's Rd
Reading
Berkshire
England
Tel. +44 734 666185

I would be particularly interested to hear about any pathological cases that 
the program appears unable to convert satisfactorily!